LoadLibrary

LoadLibrary maps the specified executable module into the address space of the calling process.

Syntax

HINSTANCE LoadLibrary(
    LPCTSTR lpLibFileName
);

Parameters

LpLibFileName

Pointer to a null-terminated string that names the executable module (either a DLL or EXE file). The name specified is the filename of the module and is not related to the name stored in the library module itself, as specified by the library keyword in the module definition (DEF) file.

If the string specifies a path but the path does not exist in the specified directory, the function fails.

If the string does not specify a path, the function uses a standard search strategy to find the file.

Name comparison is case-sensitive.

The length of lpLibFileName should not be greater then MAX_PATH.

For RTDLLs, no path is required, but the RTDLL should be registered.

Return Values

A handle to the module if the function succeeds, NULL if the function fails

To get extended error information, call GetLastError.

Remarks

LoadLibrary can be used to map a DLL module and return a handle that can be used in GetProcAddress to get the address of a DLL function.

NOTE: Do not use LoadLibrary to run an EXE file.

If the module's DLL is not already mapped for the calling process, the system calls the DLL's DllMain function with the DLL_PROCESS_ATTACH value.

If the DLL's entry-point function does not return TRUE, LoadLibrary fails and returns NULL.

NOTE: It is not safe to call LoadLibrary from DllMain.

Module handles are not global or inheritable. A call to LoadLibrary by one process does not produce a handle that another process can use, for example, in calling GetProcAddress. The other process must make its own call to LoadLibrary for the module before calling GetProcAddress.

If no filename extension is specified in the lpLibFileName parameter, the default library extension .DLL is appended. However, the filename string can include a trailing point character (.) to indicate that the module name has no extension. When no path is specified, the function searches for loaded modules whose base name matches the base name of the module to be loaded. If the name matches, the load succeeds. Otherwise, the function searches for the file in the following sequence:

The directory from which the application loaded.
The current directory.
The 32-bit Windows system directory. (Use the GetSystemDirectory function to get the path of this directory. The name of this directory is SYSTEM32.)
The 16-bit Windows system directory. There is no function that obtains the path of this directory, but it is searched. The name of this directory is SYSTEM. Use the GetWindowsDirectory function to get the path of this directory. The directories that are listed in the PATH environment variable. The first directory searched is the one directory containing the image file used to create the calling process (for more information, see CreateProcess in the Microsoft SDK documentation). Doing this allows private dynamic-link library (DLL) files associated with a process to be found without adding the process's installed directory to the PATH environment variable.

The Visual C++ compiler supports a syntax that enables you to declare thread-local variables: _declspec(thread). If you use this syntax in a DLL, you will not be able to load the DLL explicitly using LoadLibrary. If your DLL will be loaded explicitly, you must use the thread local storage functions instead of _declspec(thread).

RTSS Environment

The following information applies to the RTSS environment.

The .exe extension and DLL names without an extension (i.e., the trailing dot convention) are not supported.
Any path specified as part of lpLibFileName is ignored. RTDLLs are loaded based on whether the filename specified matches an existing, registered RTDLL.
DLLs must be registered through "RTSSRun /dll <image name>" before they can be successfully accessed with LoadLibrary.
RTSS objects and RTDLLs are case-sensitive. So if you are calling LoadLibrary on an RTDLL, use the same case used when registering the DLL.
_declspec(thread) is not supported.